---
layout: docs
page_title: Nomad namespace specification
description: |-
  Learn about Nomad's namespace specification. Review namespace parameters. Configure capabilities, node pools, Vault, and Consul.
---

# Nomad namespace specification

A Nomad namespace is a way to segment jobs and their associated objects from
other jobs and other cluster users. Specify Nomad namespaces as HCL files and
submit them with the [`nomad namespace apply`][cli_ns_apply] CLI command.
Unlike [job specifications][jobspecs], namespace specifications do not support
[HCL2][hcl2] features like functions.

In [federated][] clusters, Nomad forwards all namespace updates to the
[`authoritative_region`][] and replicates the updates to non-authoritative
regions. This requires that you have bootstrapped ACLs in the authoritative
region.

Example namespace specification:

```hcl
name        = "prod-eng"
description = "Namespace for production workloads."

# Quotas are a Nomad Enterprise feature.
quota = "eng"

meta {
  owner = "eng"
}

capabilities {
  enabled_task_drivers   = ["java", "docker"]
  disabled_task_drivers  = ["raw_exec"]
  enabled_network_modes  = ["bridge", "cni/custom"]
  disabled_network_modes = ["host"]
}

# Node Pool configuration is a Nomad Enterprise feature.
node_pool_config {
  default = "prod"
  allowed = ["all", "default"]
}

# Vault configuration is a Nomad Enterprise feature.
vault {
  default = "default"
  allowed = ["default", "infra"]
}

# Consul configuration is a Nomad Enterprise feature.
consul {
  default = "default"
  allowed = ["all", "default"]
}
```

## Parameters

- `name` `(string: <required>)` - Specifies the namespace to create or update.

- `description` `(string: "")` - Specifies an optional human-readable
  description of the namespace.

- `quota` `(string: "")` <EnterpriseAlert inline /> - Specifies a quota to
  attach to the namespace.

- `meta` `(object: null)` - Optional object with string keys and values of
  metadata to attach to the namespace. Namespace metadata is not used by Nomad
  and is intended for use by operators and third party tools.

- `capabilities` <code>([Capabilities](#capabilities-parameters): &lt;optional&gt;)</code> -
  Specifies capabilities allowed in the namespace. These values are checked at
  job submission.

- `node_pool_config` <code>([NodePoolConfiguration](#node_pool_config-parameters): &lt;optional&gt;)</code> <EnterpriseAlert inline /> -
  Specifies node pool configurations. These values are checked at job
  submission.

- `vault` <code>([Vault](#vault-parameters): &lt;optional&gt;)</code> <EnterpriseAlert inline /> -
  Specifies which Vault clusters are allowed to be used from this
  namespace. These values are checked at job submission.

- `consul` <code>([Consul](#consul-parameters): &lt;optional&gt;)</code> <EnterpriseAlert inline /> -
  Specifies which Consul clusters are allowed to be used from this
  namespace. These values are checked at job submission.

### `capabilities` parameters

- `enabled_task_drivers` `(array<string>: [])` - List of task drivers allowed
  in the namespace. If empty all task drivers are allowed.

- `disabled_task_drivers` `(array<string>: [])` - List of task drivers disabled
  in the namespace.

- `enabled_network_modes` `(array<string>: [])` - List of network modes allowed
  in the namespace. If empty all network modes are allowed.

- `disabled_network_modes` `(array<string>: [])` - List of network modes disabled
  in the namespace.

### `node_pool_config` parameters <EnterpriseAlert inline />

- `default` `(string: "default")` - Specifies the node pool to use for jobs or
  dynamic host volumes in this namespace that don't define a node pool in their
  specification.

- `allowed` `(array<string>: nil)` - Specifies the node pools that jobs or
  dynamic host volumes in this namespace are allowed to use. By default, all
  node pools are allowed. If an empty list is provided only the namespace's
  default node pool is allowed. This field supports wildcard globbing through
  the use of `*` for multi-character matching. This field cannot be used with
  `denied`.

- `denied` `(array<string>: nil)` - Specifies the node pools that jobs or
  dynamic host volumes in this namespace are not allowed to use. This field
  supports wildcard globbing through the use of `*` for multi-character
  matching. If specified, jobs and dynamic host volumes are allowed to use any
  node pool, except for those that match any of these patterns. This field
  cannot be used with `allowed`.

### `vault` parameters <EnterpriseAlert inline />

- `default` `(string: "default")` - Specifies the Vault cluster to use for jobs
  in this namespace that don't define a Vault cluster in their specification.

- `allowed` `(array<string>: nil)` - Specifies the Vault clusters that are
  allowed to be used by jobs in this namespace. By default, all Vault clusters
  are allowed.  If an empty list is provided only the namespace's default Vault
  cluster is allowed. This field supports wildcard globbing through the use of
  `*` for multi-character matching. This field cannot be used with `denied`.

- `denied` `(array<string>: nil)` - Specifies the Vault clusters that are not
  allowed to be used by jobs in this namespace. This field supports wildcard
  globbing through the use of `*` for multi-character matching. If specified,
  any Vault cluster is allowed to be used, except for those that match any of
  these patterns. This field cannot be used with `allowed`.

### `consul` parameters <EnterpriseAlert inline />

- `default` `(string: "default")` - Specifies the Consul cluster to use for jobs
  in this namespace that don't define a Consul cluster in their specification.

- `allowed` `(array<string>: nil)` - Specifies the Consul clusters that are
  allowed to be used by jobs in this namespace. By default, all Consul clusters
  are allowed.  If an empty list is provided only the namespace's default Consul
  cluster is allowed. This field supports wildcard globbing through the use of
  `*` for multi-character matching. This field cannot be used with `denied`.

- `denied` `(array<string>: nil)` - Specifies the Consul clusters that are not
  allowed to be used by jobs in this namespace. This field supports wildcard
  globbing through the use of `*` for multi-character matching. If specified,
  any Consul cluster is allowed to be used, except for those that match any of
  these patterns. This field cannot be used with `allowed`.

## Resources

Visit the [Nomad namespaces
tutorial](/nomad/docs/govern/namespaces) to learn how to create
and use Nomad namespaces

[cli_ns_apply]: /nomad/commands/namespace/apply
[hcl2]: /nomad/docs/reference/hcl2
[jobspecs]: /nomad/docs/job-specification
[federated]: //nomad/docs/deploy/clusters/federate-regions
[`authoritative_region`]: /nomad/docs/configuration/server#authoritative_region
